Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (711755f) to head (a245860).

@@            Coverage Diff             @@
##            master     #1336    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files          211       212     +1     
  Lines         7014      7267   +253     
  Branches      1398      1423    +25     
==========================================
+ Hits          7014      7267   +253     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

Hey @jamaljsr @Abdulkbk, I would appreciate a review when you get time.

Hey @Jem256 This is a fantastic feature. We've received many requests for Tor support over the year. Thanks you so much for tackling this.

I've done some functional testing and have a bit of feedback/questions:

1. I had to rebuild the docker images locally in order to get the nodes to start up. This is fine, but we'll need to also be sure to push new images to Docker Hub for all node versions currently supported by Polar. It would be good to add this as a TODO (for me) in the PR description since this feature won't work without doing this.
2. You currently have Tor support for Bitcoin Core, LND, and Core Lightning. Do you plan to add Terminal and Eclair, or is there some explanation for why these cannot be included?
3. What is the best way to confirm that the Tor connections are functioning properly for each node? Are there any tools/commands we can run from outside the network to verify it works? I can see the services running in the logs, but are the LN/BTC nodes actually using tor?
4. When I add multiple Bitcoin Core nodes, they are not syncing their chains with each other. When i mine blocks on one node, the block height on the others do not increase. I also don't see the onion address in the sidebar for these.
5. The Tor toggle in the NetworkActions toolbar feels too prominent for it's potential use. Since I suspect this feature will be used by a minority of users, I would prefer to place this toggle inside of the 3-dot dropdown menu instead. It's shouldn't be front & center next to the Start button.
6. I like the onion icons on each node. They look great when there are no channels, but once a node has channels, the placement of the icon feels off.
   

Thanks for the PR @Jem256. I also did some functional tests.

1. I run a test with 2 bitcoin nodes, and they're not syncing. I run bitcoin-cli getpeerinfo, and it seems they don't see each other on the network.
2. I noticed that creating a channel when TOR is enabled is not possible, complains about insufficient funds even though the option Deposit enough sats to carol to fund the channel is selected (works when TOR is not enabled).
3. When a node is added to the network, if TOR is enabled globally, the new node should, by default, allow TOR.

Questions:

1. I noticed that when I connect an LND and a CLN as peers, LND still sees the cleartext address of the CLN lncli listpeers. Do you know if this is the correct behaviour?.

I will look deeply into the code but for now these are my observations.

Hey @Jem256 This is a fantastic feature. We've received many requests for Tor support over the year. Thanks you so much for tackling this.

I've done some functional testing and have a bit of feedback/questions:

1. I had to rebuild the docker images locally in order to get the nodes to start up. This is fine, but we'll need to also be sure to push new images to Docker Hub for all node versions currently supported by Polar. It would be good to add this as a TODO (for me) in the PR description since this feature won't work without doing this.
2. You currently have Tor support for Bitcoin Core, LND, and Core Lightning. Do you plan to add Terminal and Eclair, or is there some explanation for why these cannot be included?
3. What is the best way to confirm that the Tor connections are functioning properly for each node? Are there any tools/commands we can run from outside the network to verify it works? I can see the services running in the logs, but are the LN/BTC nodes actually using tor?
4. When I add multiple Bitcoin Core nodes, they are not syncing their chains with each other. When i mine blocks on one node, the block height on the others do not increase. I also don't see the onion address in the sidebar for these.
5. The Tor toggle in the NetworkActions toolbar feels too prominent for it's potential use. Since I suspect this feature will be used by a minority of users, I would prefer to place this toggle inside of the 3-dot dropdown menu instead. It's shouldn't be front & center next to the Start button.
6. I like the onion icons on each node. They look great when there are no channels, but once a node has channels, the placement of the icon feels off.
   

1. This has been done.
2. I have added eclair support. However, I have not found documentation on Tor regarding Terminal. Is the implementation similar to LND?
3. So far, I have been using the logs and respective node CLI to check if a Tor address is advertised. I shall add another way to test this before the next review.
4. Since bitcoin core doesn't announce local addresses on regtest, I am still trying to figure out how we get addresses for these nodes. I think this is what is causing the issue.
   5 & 6 . Will improve these

1. I noticed that when I connect an LND and a CLN as peers, LND still sees the cleartext address of the CLN lncli listpeers. Do you know if this is the correct behaviour?.

This is not the correct behaviour. I realised my current implementation is hybrid instead of Tor only. I'll improve this

2. I have added eclair support. However, I have not found documentation on Tor regarding Terminal. Is the implementation similar to LND?

Terminal is just a wrapper around LND (plus the other daemons). LND is running inside of the Terminal process. So all of the LND config flags works for Terminal. You just have to add an lnd. prefix to the flag name. Ex: --tor.active becomes --lnd.tor.active.

Greptile Summary

This PR adds comprehensive Tor support across all node types in Polar (bitcoind, LND, Core Lightning, Eclair, litd), enabling users to test .onion services in their local Lightning Network simulations. The implementation spans Docker configuration, state management, UI components, and service layer changes.

Key changes:

• Each Docker image now includes the Tor daemon, started conditionally via ENABLE_TOR environment variable in the entrypoint scripts
• New enableTor property on LightningNode and BitcoinNode types, persisted across network save/load cycles
• Network-wide Tor toggle (in the dropdown menu) and per-node Tor toggle (in context menu and actions tab) with confirmation modals and restart handling
• Dynamic command generation via applyTorFlags / getEffectiveCommand to inject/remove Tor-specific CLI flags
• Onion icon overlay on the network designer chart for Tor-enabled nodes
• Updated ConnectTab for both bitcoin and lightning nodes to display .onion P2P addresses
• Moved connectPeers for bitcoin nodes into the store layer with Tor-aware address resolution
• Good test coverage with new test files and additions to existing suites

Issues found:

• Missing await on actions.save() in toggleTorForNode creates a race condition where saveComposeFile may read stale state
• The -onlynet=onion bitcoind flag will prevent mixed-mode peer connectivity (Tor + non-Tor nodes in the same network)
• Unconditional usermod -a -G debian-tor in entrypoint scripts (bitcoind, lnd, clightning, litd) will fail with set -e if the group doesn't exist, unlike eclair which has a guard
• Inconsistent /var/lib/tor permissions in litd entrypoint (chmod 755 vs chmod 700 everywhere else)
• Bitcoin ConnectTab may display undefined for P2P host before node info loads

Confidence Score: 3/5

• Well-structured feature with good test coverage, but several issues in Docker entrypoints and a missing await could cause runtime failures
• The PR is architecturally sound and follows existing patterns well. However, the missing await on actions.save() is a real bug that could lead to stale state, the -onlynet=onion flag may break mixed-mode networks, and the unconditional usermod calls in 4 of 5 entrypoints could cause container startup failures. These issues are fixable but should be addressed before merging.
• Pay close attention to src/store/models/network.ts (missing await), src/utils/network.ts (-onlynet=onion flag), docker/bitcoind/docker-entrypoint.sh, docker/lnd/docker-entrypoint.sh, docker/clightning/docker-entrypoint.sh, and docker/litd/docker-entrypoint.sh (unconditional usermod and inconsistent permissions)

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User toggles Tor] --> B{Network-wide or Per-node?}
    B -->|Network-wide| C[NetworkActions: handleTorToggle]
    B -->|Per-node| D[TorButton: showConfirmModal]
    
    C --> E[network.toggleTorForNetwork]
    E --> F[setAllNodesTor - set enableTor on all nodes]
    F --> G[save network state]
    G --> H[saveComposeFile - regenerate docker-compose.yml]
    
    D --> I[network.toggleTorForNode]
    I --> J{Node started?}
    J -->|Yes| K[toggleNode - stop node]
    J -->|No| L[setNodeTor - set enableTor]
    K --> L
    L --> M[save network state]
    M --> N[saveComposeFile]
    N --> O{Was started?}
    O -->|Yes| P[toggleNode - restart node]
    O -->|No| Q[Done]
    P --> Q
    
    H --> R[ComposeFile: applyTorFlags + ENABLE_TOR env]
    N --> R
    R --> S[Docker entrypoint: conditionally start Tor daemon]
    S --> T{ENABLE_TOR=true?}
    T -->|Yes| U[Start Tor + Hidden Service]
    T -->|No| V[Skip Tor setup]
    
    style A fill:#f9f,stroke:#333
    style Q fill:#9f9,stroke:#333
    style U fill:#ff9,stroke:#333

_{Last reviewed commit: 759415b}

I had to rebuild the docker images locally in order to get the nodes to start up. This is fine, but we'll need to also be sure to push new images to Docker Hub for all node versions currently supported by Polar. It would be good to add this as a TODO (for me) in the PR description since this feature won't work without doing this.

This was done.

You currently have Tor support for Bitcoin Core, LND, and Core Lightning. Do you plan to add Terminal and Eclair, or is there some explanation for why these cannot be included?

All nodes are now supported. However, opening channels in Eclair is crushing. Related to #1212 This is something i am investigating.

When I add multiple Bitcoin Core nodes, they are not syncing their chains with each other. When i mine blocks on one node, the block height on the others do not increase. I also don't see the onion address in the sidebar for these.

Tor processes are slow and this is what affects the syncing. I have increased the delay time on monitorstartup to somewhat improve this especially for peer connections. However, block propagation via tor is still slow. It eventually resolves itself but I dont know how to make it better

The Tor toggle in the NetworkActions toolbar feels too prominent for it's potential use. Since I suspect this feature will be used by a minority of users, I would prefer to place this toggle inside of the 3-dot dropdown menu instead. It's shouldn't be front & center next to the Start button.

This was done.

I like the onion icons on each node. They look great when there are no channels, but once a node has channels, the placement of the icon feels off.

This was improved. Channels don't throw the icon placement off anymore.

What is the best way to confirm that the Tor connections are functioning properly for each node? Are there any tools/commands we can run from outside the network to verify it works? I can see the services running in the logs, but are the LN/BTC nodes actually using tor?

1. lncli --rpcserver=<grpc host> --tlscertpath=<> --macaroonpath=<> getinfo
   Expected: find a .onion address only in the addresses field.
   listpeers should show .onion address for all outbound connections
   The premise of getinfo and looking at peers is to confirm that connections are no longer via docker bridge but tor socks and tor is actually being used by the nodes through published addresses.

2. torify nc -zv example.onion 9735 (corresponding port depending on implementation)
   Expected: Connection to example.onion (127.42.42.0) 9735 port [tcp/*] succeeded! This test verifies external reachability of the ports outside the network.

   @jamaljsr

I run a test with 2 bitcoin nodes, and they're not syncing. I run bitcoin-cli getpeerinfo, and it seems they don't see each other on the network.

This is now working. However, syncing is a bit slow because tor is slow. I'd appreciate suggestions on how to improve this

I noticed that creating a channel when TOR is enabled is not possible, complains about insufficient funds even though the option Deposit enough sats to carol to fund the channel is selected (works when TOR is not enabled).

This is now working.

When a node is added to the network, if TOR is enabled globally, the new node should, by default, allow TOR.

This was implemented.

I noticed that when I connect an LND and a CLN as peers, LND still sees the cleartext address of the CLN lncli listpeers. Do you know if this is the correct behaviour?.

Outbound peers ("inbound": false) show .onion addresses with "network": "onion"
addrbind for outbound peers is 127.0.0.1:port, meaning the connection left through the local Tor SOCKS proxy.
Inbound peers show 127.0.0.1:port address because Tor is anonymizing the connecting peer. When a remote node connects to you via Tor, the connection arrives at your machine as a local TCP socket.
What we don't expect to see are docker bridge IPs (eg 172.18.0.7:port)

cc @Abdulkbk